<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD><TITLE>Tcl_Alloc manual page - Tcl Library Procedures</TITLE>
<link rel="stylesheet" href="../docs.css" type="text/css" media="all">
</HEAD>
<BODY><H2><a href="../contents.htm">Tcl8.6.11/Tk8.6.11 Documentation</a> <small>&gt;</small> <a href="contents.htm">Tcl C API</a> <small>&gt;</small> Alloc</H2>
<H3><A HREF="../UserCmd/contents.htm">Tcl/Tk Applications</A> | <A HREF="../TclCmd/contents.htm">Tcl Commands</A> | <A HREF="../TkCmd/contents.htm">Tk Commands</A> | <A HREF="../ItclCmd/contents.htm">[incr Tcl] Package Commands</A> | <A HREF="../SqliteCmd/contents.htm">SQLite3 Package Commands</A> | <A HREF="../TdbcCmd/contents.htm">TDBC Package Commands</A> | <A HREF="../TdbcmysqlCmd/contents.htm">tdbc::mysql Package Commands</A> | <A HREF="../TdbcodbcCmd/contents.htm">tdbc::odbc Package Commands</A> | <A HREF="../TdbcpostgresCmd/contents.htm">tdbc::postgres Package Commands</A> | <A HREF="../TdbcsqliteCmd/contents.htm">tdbc::sqlite3 Package Commands</A> | <A HREF="../ThreadCmd/contents.htm">Thread Package Commands</A> | <A HREF="../TclLib/contents.htm">Tcl C API</A> | <A HREF="../TkLib/contents.htm">Tk C API</A> | <A HREF="../ItclLib/contents.htm">[incr Tcl] Package C API</A> | <A HREF="../TdbcLib/contents.htm">TDBC Package C API</A></H3>
<DL>
<DD><A HREF="Alloc.htm#M2" NAME="L15">NAME</A>
<DL><DD>Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc &mdash; allocate or free heap memory</DD></DL>
<DD><A HREF="Alloc.htm#M3" NAME="L16">SYNOPSIS</A>
<DL>
<DD><B>#include &lt;tcl.h&gt;</B>
<DD>char *
<DD><B>Tcl_Alloc</B>(<I>size</I>)
<DD>void
<DD><B>Tcl_Free</B>(<I>ptr</I>)
<DD>char *
<DD><B>Tcl_Realloc</B>(<I>ptr, size</I>)
<DD>char *
<DD><B>Tcl_AttemptAlloc</B>(<I>size</I>)
<DD>char *
<DD><B>Tcl_AttemptRealloc</B>(<I>ptr, size</I>)
<DD>char *
<DD><B>ckalloc</B>(<I>size</I>)
<DD>void
<DD><B>ckfree</B>(<I>ptr</I>)
<DD>char *
<DD><B>ckrealloc</B>(<I>ptr, size</I>)
<DD>char *
<DD><B>attemptckalloc</B>(<I>size</I>)
<DD>char *
<DD><B>attemptckrealloc</B>(<I>ptr, size</I>)
</DL>
<DD><A HREF="Alloc.htm#M4" NAME="L17">ARGUMENTS</A>
<DL class="arguments">
</DL>
<DD><A HREF="Alloc.htm#M5" NAME="L18">DESCRIPTION</A>
<DD><A HREF="Alloc.htm#M6" NAME="L19">KEYWORDS</A>
</DL>
<H3><A NAME="M2">NAME</A></H3>
Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc &mdash; allocate or free heap memory
<H3><A NAME="M3">SYNOPSIS</A></H3>
<B>#include &lt;tcl.h&gt;</B><BR>
char *<BR>
<B>Tcl_Alloc</B>(<I>size</I>)<BR>
void<BR>
<B>Tcl_Free</B>(<I>ptr</I>)<BR>
char *<BR>
<B>Tcl_Realloc</B>(<I>ptr, size</I>)<BR>
char *<BR>
<B>Tcl_AttemptAlloc</B>(<I>size</I>)<BR>
char *<BR>
<B>Tcl_AttemptRealloc</B>(<I>ptr, size</I>)<BR>
char *<BR>
<B>ckalloc</B>(<I>size</I>)<BR>
void<BR>
<B>ckfree</B>(<I>ptr</I>)<BR>
char *<BR>
<B>ckrealloc</B>(<I>ptr, size</I>)<BR>
char *<BR>
<B>attemptckalloc</B>(<I>size</I>)<BR>
char *<BR>
<B>attemptckrealloc</B>(<I>ptr, size</I>)<BR>
<H3><A NAME="M4">ARGUMENTS</A></H3>
<DL class="arguments">
<DT>unsigned int <B>size</B> (in)<DD>
Size in bytes of the memory block to allocate.
<P><DT>char <B>*ptr</B> (in)<DD>
Pointer to memory block to free or realloc.
<P></DL>
<H3><A NAME="M5">DESCRIPTION</A></H3>
These procedures provide a platform and compiler independent interface
for memory allocation.  Programs that need to transfer ownership of
memory blocks between Tcl and other modules should use these routines
rather than the native <B>malloc()</B> and <B>free()</B> routines
provided by the C run-time library.
<P>
<B>Tcl_Alloc</B> returns a pointer to a block of at least <I>size</I>
bytes suitably aligned for any use.
<P>
<B>Tcl_Free</B> makes the space referred to by <I>ptr</I> available for
further allocation.
<P>
<B>Tcl_Realloc</B> changes the size of the block pointed to by
<I>ptr</I> to <I>size</I> bytes and returns a pointer to the new block.
The contents will be unchanged up to the lesser of the new and old
sizes.  The returned location may be different from <I>ptr</I>.  If
<I>ptr</I> is NULL, this is equivalent to calling <B>Tcl_Alloc</B> with
just the <I>size</I> argument.
<P>
<B>Tcl_AttemptAlloc</B> and <B>Tcl_AttemptRealloc</B> are identical in
function to <B>Tcl_Alloc</B> and <B>Tcl_Realloc</B>, except that
<B>Tcl_AttemptAlloc</B> and <B>Tcl_AttemptRealloc</B> will not cause the Tcl
interpreter to <B>panic</B> if the memory allocation fails.  If the
allocation fails, these functions will return NULL.  Note that on some
platforms, but not all, attempting to allocate a zero-sized block of
memory will also cause these functions to return NULL.
<P>
The procedures <B>ckalloc</B>, <B>ckfree</B>, <B>ckrealloc</B>,
<B>attemptckalloc</B>, and <B>attemptckrealloc</B> are implemented
as macros.  Normally, they are synonyms for the corresponding
procedures documented on this page.  When Tcl and all modules
calling Tcl are compiled with <B>TCL_MEM_DEBUG</B> defined, however,
these macros are redefined to be special debugging versions
of these procedures.  To support Tcl's memory debugging within a
module, use the macros rather than direct calls to <B>Tcl_Alloc</B>, etc.

<H3><A NAME="M6">KEYWORDS</A></H3>
<A href="../Keywords/A.htm#alloc">alloc</A>, <A href="../Keywords/A.htm#allocation">allocation</A>, <A href="../Keywords/F.htm#free">free</A>, <A href="../Keywords/M.htm#malloc">malloc</A>, <A href="../Keywords/M.htm#memory">memory</A>, <A href="../Keywords/R.htm#realloc">realloc</A>, <A href="../Keywords/T.htm#TCL_MEM_DEBUG">TCL_MEM_DEBUG</A>
<div class="copy">Copyright &copy; 1995-1996 Sun Microsystems, Inc.
</div>
</BODY></HTML>
